System Booster/System Booster.iso/Archives/Shells/Matrix11.lha/man/Matrix.MAN

Text File | 1994-01-07 | 12.8 KB | 382 lines

MATRIX                USER COMMANDS            06-Jan-1993


NAME
    matrix - menu system for AXsh (version 1.1)

SYNOPSIS
    matrix [[menufile] [prompt] | chat | abort | page <text> |
        force <command>]

DESCRIPTION
    Matrix is a replacement for the Topic menuing system by Markku
    'Hack' Mellanen.  I used Topic for half a year, but eventually
    became frustrated with its quirks and lack of expandability
    and got tired of hex-editing in my corrections, so I wrote my own.
    Matrix is intended for use with AXsh, but it can be used from
    AmigaDOS or another BBS if you want (consult the OTHER SYSTEMS
    section for this).  Matrix is largely compatible with Topic, but
    it also provides a large number of extensions.  Here's a summary
    of the differences:

    - full shell support (local/global variables, piping, etc)
    - all options can be combined
    - better support for submenus
    - all actions by users are logged
    - expert/verbose mode selection
    - instant menu redrawing, pause option
    - support for "timeout" utility, detection of AXsh:etc/nologin
    - commands to run from outside for page, forced chat, and abort
    - user-definable abort/chat/force commands
    - attempts to notice carrier loss and acts accordingly

    As of Jan 1994, Timeout (a time limit utility) is not ready for
    release, so ignore references to it here.

NEW FEATURES
    Matrix v1.1 is a stopgap release to fix the massive security bug
    I realized had been in it (and Topic) all along.  Namely, if
    the user decided to create his own menu file...perhaps with a menu
    item like "axsh:bin/axsh -con -user root"...  Need I say more?
    Matrix now supports a MATRIX_DIR variable where the sysop can enter
    legal directories for menus.

    The other changes are also primarily security/safety features.
    Being an intermediate release, the code actually has some of
    the nifty client/server multitask code I was working on, but it's
    #ifdef'd out and never invoked.

    Features added or significantly changed in Matrix since v1.0:

    - Aforementioned security bug fixed with ENV:MATRIX_DIR variable.
    - Users kicked out of Matrix if 5 invalid commands are given.  This
      is an attempt to deal with carrier drops, which often cause the
      modem to spew/repeat junk for a while, making Topic/Matrix 1.0
      loop endlessly.
    - CTRL-C processed instead of just aborting instantly.
    - Users cannot enter MSG_* in menus.
    - All gets() replaced with fgets(stdin), now users cannot crash
      machine simply by entering tons of junk.
    - Superuser rights given to all users with one of these accesslevels:
      assistant, superuser, wizard, system

    I attempted to implent an autologout system, bu evidently WaitForChar()
    doesn't like AXsh or serial input, so I had to resort to the current
    approach.  I'll try it with a different approach for v2.0.

REQUIREMENTS
    Matrix requires an Amiga with Kickstart 2.0 or higher and an input
    device of some kind (ie. a serial port or a keyboard).

GENERAL
    Matrix relies on specially formatted menu files.  The default
    menu is "axsh:etc/menu/main", and the default prompt is
    "Choice (Q to quit)", they can be changed with command line
    arguments.

    Matrix's logfiles can be found in AXsh:etc/adm/ in the format
    LogDDMMYY-Matrix.  All logs for one day are lumped together,
    since users have a tendency of entering and exiting the menus
    many times in a single session, which would result in millions
    of tiny logs if they were separate.

    The menus from my own system are included.  Feel free to look at
    them for guidance and even use in your own system, provided that
    you at least delete the "Brahman" logos.  :)  Source code is
    also included, more on that later...  The "sc" directory contains
    two scripts, one for launching Matrix for sysops, the other
    for launching Matrix for normal users.  I suggest adding a
    line like "alias menu AXsh:sc/launchmatrix" to etc/GlobalLogin,
    so users can simply type "menu" to get into the menu system.

    To convert from Topic to Matrix, all you have to do is add
    a %exit command to your main menu, like this:

    q
    %exit
    ---

    However, that will mostly definately not be all you'll want to
    do.  :)  As of v1.1, you may also need to add the following command
    to your AXsh setup:

    SetEnv MATRIX_DIR <dir> [dir...]

    Where "dir" is a legal directory for Matrix menu files.  If you don't
    have MATRIX_DIR, Matrix defaults to only allowing menus from
    AXsh:etc/menu and AXsh:etc/adm.

MENU FILE SETUP
    Matrix's menu files are almost identical to Topic's.
    The format is this:

    Menu text (ANSI codes allowed)
    #
    <key>
    <command> [arguments]
    <options>[extended-options][special arguments]
    ...repeat...
    #

    This is almost the same as Topic.  The key can be one or more
    letters, but unlike Topic, they're case sensitive.  The command
    (which should have a full path) can be followed by arguments,
    since I found Topic's method of putting them after the options
    cumbersome.  Options are discussed later, but after them, there
    are either more arguments which simply get appended to the command
    string, or special arguments for options.  Lines of white space
    are not allowed and will confuse Matrix badly; white space at
    the end of lines is read in.

OPTIONS
    Matrix follows Topic's options format with some extensions.
    The format is crude, but changing it drastically and retaining
    compatability would have been difficult.  Unlike Topic, you
    can mix the options, for example raw mode with user argument is
    possible in Matrix but impossible in Topic.  At any rate, the empty
    options line should look like this:

    ---    *OR*    ---x--

    Filled up with the flags:

    rp?    *OR*    rp?xzm

    This is what the flags (which must be in the right place and order)
    mean:

    r    Raw mode, ie. no buffering.  Required by some programs
        like consolechat and SpaceDoor.

    p    Check path for ":", "/" or "$" marks in user's argument.
        "$" is checked since variables are only expanded after they
        are passed out of Matrix, and a sneaky user could define
        one to contain a path.  WARNING: wildcards are *not*
        scanned.  Make sure users can only load Matrix from
        safe places.  Only useful with ?-flag.

    ?    Get argument(s) from user.  The question string is placed
        in the special-arguments section.

    x    Signifies that extended options follow.

    z    Wait for a keypress after command finishes (unless in Expert mode).

    m    Set for %menu commands (more in next section).

    Some examples:

    w            Run 'who' and wait for a key
    axsh:bin/who
    ---xz-

    d            Ask for a file/pattern to delete, check to
    c:delete        make sure it's not a path, then delete the
    -p?Filename:        file.

    c            Run consolechat in raw mode.
    axsh:bin/cc
    r--

SPECIAL COMMANDS
    Matrix also introduces several special commands.  They are the
    following:

    %exit - Exits Matrix.

    %menu <menufile> - Use this instead of just loading another copy
    of Matrix, it's far more efficient and the logfiles will not get
    mixed up.

    You must specify the extended option "m" in the 6th place.  To use
    a prompt other than the default, place it in the special arguments
    field.  Note: a space after the prompt *is* noticed by Matrix!
    Example:

        f
        %menu axsh:etc/menu/file
        ---x-mFile Menu]

    %quit - Same as exit.

    %xprt - Toggles expert mode on and off.  Selection is not saved to
    disk, although user is told how to do it.  Local variable "expert"
    is affected.


EXTERNAL COMMANDS
    At the moment, Matrix has four external commands that can be
    run from outside Matrix to affect it.  Matrix will notice them
    every time the menu is redisplayed and after a command returns.
    Superuser commands can be run if the user is an assistant,
    superuser, wizard or system.  The commands are:

    matrix abort        Kicks user out of Matrix.
                Superuser only.

    matrix chat        Forces the Matrix user into chat.
                Superuser only.

    matrix force <cmd>    Forces a CLI command to be executed.
                Superuser only.

    matrix page <text>    The text will be displayed in Matrix.

    Note that force's command and page's text do not need to be
    surrounded by quote marks, although they may contain them in need.
    The paging system is built in; however, chat and abort can be
    redefined by the user.  To redefine chat, add a command whose key
    is "MSG_CHAT"; to redefine abort, add a command whose key is
    "MSG_ABRT".  MSG_ABRT is also run if time runs out, the inactivity
    limit is crossed, or AXsh:etc/nologin is detected.  The defaults are
    the following:

    Chat:    MSG_CHAT
        AXsh:bin/chat
        r--

    Abort:    MSG_ABRT
        %exit
        ---

    The "Superuser forced..." texts are shown automatically and cannot
    be changed (yet).  In addition, only the last external command sent
    will be executed.

TIPS AND TRICKS
    It's fully legal to assign multiple commands to the same key
    (they'll be executed in sequential order from top to bottom) or
    to execute an AmigaDOS script from a key.  However, MSG_*
    keys cannot be stacked, use a script if you need to get around
    this.

    If you want to have a user-defined command in a menu, you can
    leave the arguments empty like this:

        u

        --?Enter command:

    Naturally, it would be smart to restrict access to such a command
    to sysops.

SECURITY
    Matrix, being independent of the AXshell, also doesn't have its
    security restrictions.  Thus, you have to be very careful not
    to let the user wreak havoc, intentionally or by accident,
    on your system.  I strongly recommend that you make sure the user
    loads it from his home directory in one of the following ways:

    Method 1, will prevent accidents but not a determined hacker

    Create a "menu" alias that executes a script like this:

    set olddir $cwd
    cd $home
    matrix random/menu "NicePrompt} "
    cd $olddir
    unset olddir

    This insures that matrix is run from home and restores the user to
    the original directory afterwards, but can be circumvented quite
    easily.

    Method 2, secure but a bit inconvinient:

    Lump all commands like "delete" and "more" in one submenu,
    then give something like this for its command:

    f
    cd $home
    ---
    f
    %menu axsh:etc/menu/file
    ---File]

    There's more.  Matrix and Topic will both happily show the
    contents of any file they are given (in a legal directory, of
    course) until they realize it's    not a menu file by hitting the end.
    Thus, leave nothing interesting in the menu directories.

    On my system, the sysops have their own menu, which gives them
    access to a whole range of dangerous goodies.  Needless to say,
    you do *not* want normal users to be able to use it...  The
    solution is simple: place the sysop menu in a directory where
    the users can't touch it!  I use AXsh:etc/adm for the sysop menu
    and AXsh:etc/menu for the normal menus.

    Remember, Matrix path checking does not stop wildcards, and things
    like "delete * all" can slip through.  This is why you must make
    sure the users are in their home directories.

OTHER SYSTEMS
    If you want to use Matrix with systems other than AXsh, the
    following local variables must be set:

    user        The user's name

    Setting this variable is recommended:

    accesslevel    Set to "superuser" for Matrix externals.

    And you will have to create the directory AXsh:etc/adm for
    logfiles.  Also, you'll probably want to redefine MSG_CHAT to
    use another program instead of AXsh:bin/chat.

FUTURE FEATURES
    In the future, I plan on adding some or all of the following:

    - a separate Topic/Matrix menu editor
    - full multi-user support
    - support for multiple external commands simultaneously, and
      replacement of crude global variable system with politically
      correct message ports
    - commands that can only be executed by users with a given
      accesslevel
    - axsh:etc/rc used to check path validity if desired
    - letting the user respond to pages
    - better support for non-AXsh systems
    - more flexibility to the Topic/Matrix menu format

AUTHOR           _
    Jani "Guru Gnosis Sahib" Poijärvi
    Internet: [e-mail]
    BBS: Brahman, [phone], USR 16800 DS, 24h/7d
             (official Matrix support site)

FILES
    bin/matrix
    etc/adm/LogDDMMYY-Matrix
    etc/menu/*

SEE ALSO
    timeout
    topic

NOTES
    AXsh internal commands (quit, write, login, etc) cannot be used
    since they're internal and Matrix is not the AXshell.  Likewise,
    the AXsh directory conventions ("..", "/", "~") are not (yet)
    understood, and AmigaDOS parsing is used.

    There is a limit of 48 commands in a single menu.  If this
    is too restrictive, redesign your menu, or change the MAX_ITEM
    #define and recompile.

    Matrix was written entirely with DICE C, and the bulk of the code
    was written in 2 days during Christmas vacation.  The source
    is included and should be reasonably portable.  Feel free to
    modify, but don't distribute modified code without permission,
    and send interesting modifications to me.  Hell, send me mail
    just to let me know you exist and that I didn't waste my
    vacation for nothing...

BUGS
    Matrix's largest bug is that multiple copies of it running at
    the same time will cause assorted havoc.  They should all *work*:
    however, external commands and logging will function highly
    erratically, if at all.  Avoid if you can, I'm planning on fixing the
    whole system for v2.0.

    Other than that, there are just undocumented features.  :)